Validating Events

​

Prerequisites

• Events have been transmitted to Flexprice
• Access to the Flexprice Admin Dashboard
• Knowledge of your feature configuration

​

Checking Event Ingestion

​

1. Navigate to Events Dashboard

1. Log into your Flexprice Admin Dashboard
2. In the left sidebar, click on Usage Tracking
3. Click on Events

• Event ID: Unique identifier for each event
• Event Name: The feature being tracked
• External Customer ID: Customer associated with the event
• Source: Origin of the event (if provided)
• Timestamp: When the event occurred

​

2. View Event Details

• All properties transmitted with the event
• Timestamp information
• Customer details
• Any additional metadata

​

Using the Event Debugger

1. Go to Usage Tracking → Event Debugger
2. You can see:
   • Events being processed in real-time
   • Any errors or warnings
   • Processing status and timing

​

Validating Aggregation

​

Check Feature Configuration

1. Go to Product Catalog → Features
2. Find your metered feature
3. Verify the configuration:
   • Event Name matches what you’re transmitting
   • Aggregation Function is set correctly
   • Aggregation Field exists in your event properties

​

Verify Event Properties

1. Event Name matches your feature exactly
2. Properties contain the aggregation field
3. Property values are the correct data type

{
  "properties": {
    "credits": 2
  }
}

​

Common Validation Issues

​

1. Events Not Appearing

• Invalid Event Name
• Missing required fields
• Customer doesn’t exist
• API key issues

• Check Event Name spelling and case
• Verify all required fields are present
• Ensure customer exists in Flexprice
• Validate API key permissions

​

2. Wrong Aggregation Values

• Aggregation field name mismatch
• Incorrect data types
• Missing properties

• Verify field name matches exactly (case-sensitive)
• Use numbers for Sum/Max, strings for Unique Count
• Ensure every event includes the required property

​

3. Events Appearing but No Billing

• Feature not added to a plan
• Customer not subscribed to the plan
• Usage reset configuration

• Add feature to a pricing plan
• Subscribe customer to the plan
• Check Usage Reset setting (Periodic vs Cumulative)

​

Testing Your Setup

​

Step-by-Step Validation

1. Transmit a Test Event
   Copy

   curl --request POST \
     --url https://api.cloud.flexprice.io/v1/events \
     --header 'Content-Type: application/json' \
     --header 'x-api-key: <your_api_key>' \
     --data '{
       "event_name": "model.usage",
       "external_customer_id": "cust-test-customer",
       "properties": {
         "credits": 1
       }
     }'
   

2. Check Event Ingestion
   • Go to Events dashboard
   • Locate your test event
   • Verify the payload is correct
3. Verify Aggregation
   • Check that the event appears in the correct billing period
   • Verify the aggregation value is as expected
4. Test Billing Impact
   • Ensure feature is in a plan
   • Subscribe customer to the plan
   • Check upcoming invoices

​

Debugging Checklist

​

✅ Event Configuration

• Feature exists and is active
• Event Name matches exactly
• Aggregation Function is correct
• Aggregation Field is set (if required)

​

✅ Event Payload

• All required fields present
• Event Name matches feature
• External Customer ID exists
• Properties contain aggregation field
• Property values are correct data type

​

✅ Customer Setup

• Customer exists in Flexprice
• External Customer ID matches
• Customer has active subscription
• Subscription includes the feature

​

✅ Billing Configuration

• Feature is added to a plan
• Plan has pricing for the feature
• Customer is subscribed to the plan
• Usage Reset setting is correct

​

Advanced Validation

​

Query Events by Customer

1. In the Events dashboard, use the filter options
2. Filter by External Customer ID
3. Review all events for that customer

​

Check Aggregated Usage

1. Go to Usage Tracking → Query
2. Select your feature
3. Choose the customer and time period
4. View aggregated usage values

​

Validate Billing Periods

• Usage should reset at the start of each billing cycle
• Check that usage accumulates correctly within the period

• Usage should keep growing across billing cycles
• Verify no unexpected resets

​

Troubleshooting Common Scenarios

​

Scenario 1: Events Transmitted but Not Counted

1. Feature configuration (Event Name, Aggregation Field)
2. Event properties (correct field name and data type)
3. Customer subscription status
4. Plan configuration

​

Scenario 2: Wrong Aggregation Values

1. Aggregation Field name matches exactly
2. Property values are correct data type
3. No duplicate or conflicting events
4. Usage Reset configuration

​

Scenario 3: Events Missing from Dashboard

1. API response status (should be 202 Accepted)
2. Event Name validity
3. Customer existence
4. API key permissions

​

Scenario 4: Unexpected Usage Resets

1. Usage Reset setting (Periodic vs Cumulative)
2. Billing cycle configuration
3. Subscription changes
4. Feature configuration changes

​

Best Practices for Validation

​

1. Test Before Production

​

2. Monitor Regularly

​

3. Use Consistent Identifiers

​

4. Include Debugging Information

{
  "event_name": "model.usage",
  "external_customer_id": "cust_123",
  "properties": {
    "credits": 2,
    "request_id": "req_abc123",
    "version": "1.0"
  },
  "source": "api"
}

​

5. Set Up Alerts

• Failed event ingestion
• Unusual usage patterns
• Missing events

​

Next Steps

1. Connect to Billing - Set up pricing and subscriptions
2. Monitor Usage - Track usage patterns and trends
3. Optimize Performance - Improve event ingestion efficiency

​

Getting Help

1. Check the Event Debugger for detailed error messages
2. Review your feature configuration carefully
3. Test with a simple event payload
4. Contact support with specific error messages and event examples